home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 076-100 / 092 / bawk / bawk.doc < prev    next >
Text File  |  1995-03-13  |  11KB  |  311 lines
  1. NAME
  2.  
  3.     bawk - text processor
  4.  
  5. SYNOPSIS
  6.  
  7.     bawk rules [file] ...
  8.     bawk -f rulefile file ...
  9.  
  10. DESCRIPTION
  11.  
  12.     Bawk is a text processing program that searches files for
  13.     specific patterns and performs "actions" for every occurrance
  14.     of these patterns.  The patterns can be "regular expressions"
  15.     as used in the UNIX "ex" editor.  The actions are expressed
  16.     using a subset of the "C" language.
  17.  
  18.     By default Bawk will interpret the first argument as a rule.
  19.     You can force bawk to take the rules from a file by using the
  20.     -f option. The following arguments are taken to be the names of
  21.     text files on which the rules are to be applied. The special file
  22.     name "-" may also be used anywhere on the command line to take
  23.     input from the standard input device.
  24.  
  25.     The command:
  26.  
  27.         bawk - prog.c - prog.h
  28.  
  29.     would read the patterns and actions rules from the standard
  30.     input, then apply them to the files "prog.c", the standard
  31.     input and "prog.h" in that order.
  32.  
  33.     The general format of a rules file is:
  34.  
  35.         <pattern> { <action> }
  36.         <pattern> { <action> }
  37.         ...
  38.  
  39.     There may be any number of these <pattern> { <action> }
  40.     sequences in the rules file.  Bawk reads a line of input from
  41.     the current input file and applies every <pattern> { <action> }
  42.     in sequence to the line.
  43.     
  44.     If the <pattern> corresponding to any { <action> } is missing,
  45.     the action is applied to every line of input.  The default
  46.     { <action> } is to print the matched input line.
  47.  
  48. PATTERNS
  49.  
  50.     The <pattern>'s may consist of any valid C expression.  If the
  51.     <pattern> consists of two expressions separated by a comma, it
  52.     is taken to be a range and the <action> is performed on all
  53.     lines of input that match the range.  <pattern>'s may contain
  54.     "regular expressions" delimited by an '@' symbol.  Regular
  55.     expressions can be thought of as a generalized "wildcard"
  56.     string matching mechanism, similar to that used by many
  57.     operating systems to specify file names.  Regular expressions
  58.     may contain any of the following characters:
  59.  
  60.         x    An ordinary character (not mentioned below)
  61.             matches that character.
  62.         '\'    The backslash quotes any character.
  63.             "\$" matches a dollar-sign.
  64.         '^'    A circumflex at the beginning of an expression
  65.             matches the beginning of a line.
  66.         '$'    A dollar-sign at the end of an expression
  67.             matches the end of a line.
  68.         '.'    A period matches any single character except
  69.             newline.
  70.         ':x'    A colon matches a class of characters described
  71.             by the character following it:
  72.         ':a'    ":a" matches any alphabetic;
  73.         ':d'    ":d" matches digits;
  74.         ':n'    ":n" matches alphanumerics;
  75.         ': '    ": " matches spaces, tabs, and other control
  76.             characters, such as newline.
  77.         '*'    An expression followed by an asterisk matches
  78.             zero or more occurrances of that expression:
  79.             "fo*" matches "f", "fo", "foo", "fooo", etc.
  80.         '+'    An expression followed by a plus sign matches
  81.             one or more occurrances of that expression:
  82.             "fo+" matches "fo", "foo", "fooo", etc.
  83.         '-'    An expression followed by a minus sign
  84.             optionally matches the expression.
  85.         '[]'    A string enclosed in square brackets matches
  86.             any single character in that string, but no
  87.             others.  If the first character in the string
  88.             is a circumflex, the expression matches any
  89.             character except newline and the characters in
  90.             the string.  For example, "[xyz]" matches "xx"
  91.             and "zyx", while "[^xyz]" matches "abc" but not
  92.             "axb".  A range of characters may be specified
  93.             by two characters separated by "-".  Note that,
  94.             [a-z] matches alphabetics, while [z-a] never
  95.             matches.
  96.  
  97.     For example, the following rules file would print every line
  98.     that contained a valid C identifier:
  99.  
  100.         @[a-zA-Z][a-zA-Z0-9]@
  101.  
  102.     And this rules file would print all lines between and including
  103.     the ones that contained the word "START" and "END":
  104.  
  105.         @START@, @END@
  106.  
  107. ACTIONS
  108.  
  109.     Actions are expressed as a subset of the C language.  All
  110.     variables are global and default to int's if not formally
  111.     declared.  Variable declarations may appear anywhere within
  112.     an action.  Only char's and int's and pointers and arrays of
  113.     char and int are allowed.  Bawk allows only decimal integer
  114.     constants to be used - no hex (0xnn) or octal (0nn). String
  115.     and character constants may contain all of the special C
  116.     escapes (\n, \r, etc.).
  117.  
  118.     Bawk supports the "if", "else", "while" and "break" flow of
  119.     control constructs, which behave exactly as in C.
  120.  
  121.     Also supported are the following unary and binary operators,
  122.     listed in order from highest to lowest precedence:
  123.  
  124.         operator           type    associativity
  125.         () []              unary   left to right
  126.         ! ~ ++ -- - * &    unary   right to left
  127.         * / %              binary  left to right
  128.         + -                binary  left to right
  129.         << >>              binary  left to right
  130.         < <= > >=          binary  left to right
  131.         == !=              binary  left to right
  132.         &                  binary  left to right
  133.         ^                  binary  left to right
  134.         |                  binary  left to right
  135.         &&                 binary  left to right
  136.         ||                 binary  left to right
  137.         =                  binary  right to left
  138.  
  139.     Comments are introduced by a '#' symbol and are terminated by
  140.     the first newline character.  The standard "/*" and "*/"
  141.     comment delimiters are not supported and will result in a
  142.     syntax error.
  143.  
  144. FIELDS
  145.  
  146.     When bawk reads a line from the current input file, the
  147.     record is automatically separated into "fields".  A field is
  148.     simply a string of consecutive characters delimited by either
  149.     the beginning or end of line, or a "field separator" character
  150.     Initially, the field separators are the space and tab character.
  151.     The special unary operator '$' is used to reference one of the
  152.     fields in the current input record (line).  The fields are
  153.     numbered sequentially starting at 1.  The expression "$0"
  154.     references the entire input line.
  155.  
  156.     Similarly, the "record separator" is used to determine the end
  157.     of an input "line", initially the newline character.
  158.     The field and record separators may be changed programatically
  159.     by one of the actions and will remain in effect until changed
  160.     again.
  161.  
  162.     If the record separator is empty then an empty line will be taken
  163.     as record separator and tab, space and newline will be used as
  164.     field separators.
  165.  
  166.     Fields behave exactly like strings; and can be used in the same
  167.     context as a character array.  These "arrays" can be considered
  168.     to have been declared as:
  169.  
  170.         char ($n)[ 200 ];
  171.  
  172.     In other words, they are 200 bytes long.  Notice that the
  173.     parentheses are necessary because the operators [] and $
  174.     associate from right to left; without them, the statement
  175.     would have parsed as:
  176.  
  177.         char $(1[ 200 ]);
  178.  
  179.     which is obviously ridiculous.
  180.  
  181.     If the contents of one of these field arrays is altered, the
  182.     "$0" field will reflect this change.  For example, this
  183.     expression:
  184.  
  185.         *$4 = 'A';
  186.  
  187.     will change the first character of the fourth field to an upper-
  188.     case letter 'A'.  Then, when the following input line:
  189.  
  190.         120 PRINT "Name         address        Zip"
  191.  
  192.     is processed, it would be printed as:
  193.  
  194.         120 PRINT "Name         Address        Zip"
  195.  
  196.     Fields may also be modified with the strcpy() function (see
  197.     below).  For example, the expression:
  198.  
  199.         strcpy( $4, "Addr." );
  200.  
  201.     applied to the same line above would yield:
  202.  
  203.         120 PRINT "Name         Addr.        Zip"
  204.  
  205. PREDEFINED VARIABLES
  206.  
  207.     The following variables are pre-defined:
  208.  
  209.         FS        Field separator (see below).
  210.         RS        Record separator (see below also).
  211.         NF        Number of fields in current input
  212.                 record (line).
  213.         NR        Number of records processed thus far.
  214.         FILENAME    Name of current input file.
  215.         BEGIN        A special <pattern> that matches the
  216.                 beginning of input text, before the
  217.                 first record is read.
  218.         END        A special <pattern> that matches the
  219.                 end of input text, after the last
  220.                 record has been read.
  221.  
  222.     Bawk also provides some useful builtin functions for string
  223.     manipulation and printing:
  224.  
  225.         printf(arg..)    Exactly the printf() function from C.
  226.         getline()    Reads the next record from the current
  227.                 input file and returns 0 on end of file.
  228.         nextfile()    Closes out the current input file and
  229.                 begins processing the next file in the
  230.                 list (if any).
  231.         strlen(s)    Returns the length of its string argument.
  232.         strcpy(s,t)    Copies the string "t" to the string "s".
  233.         strcmp(s,t)    Compares the "s" to "t" and returns 0 if
  234.                 they match.
  235.         toupper(c)    Returns its character argument converted
  236.                 to upper-case.
  237.         tolower(c)    Returns its character argument converted
  238.                 to lower-case.
  239.         match(s,@re@)    Compares the string "s" to the regular
  240.                 expression "re" and returns the number
  241.                 of matches found (zero if none).
  242.  
  243. EXAMPLES
  244.  
  245.     The following rules file will scan a C program, counting the
  246.     number of mismatched parentheses, brackets, and braces.
  247.  
  248.         @[()\[\]{}]@
  249.         {
  250.             parens = parens + match( $0, @(@ );
  251.             parens = parens - match( $0, @)@ );
  252.             bracks = bracks + match( $0, @\[@ );
  253.             bracks = bracks - match( $0, @]@ );
  254.             braces = braces + match( $0, @{@ );
  255.             braces = braces - match( $0, @}@ );
  256.         }
  257.         END { printf("parens=%d, brackets=%d, braces=%d\n",
  258.                 parens, bracks, braces );
  259.         }
  260.  
  261.     This program will capitalize the first word in every sentence of
  262.     a document:
  263.  
  264.         BEGIN
  265.         {
  266.             strcpy(RS,".");  # set record separator to a period
  267.         }
  268.         {
  269.             if ( match( $1, @^[a-z]@ ) )
  270.                 *$1 = toupper( *$1 );
  271.             printf( "%s\n", $0 );
  272.         }
  273.  
  274. LIMITATIONS
  275.  
  276.     Bawk was originally written in BDS C, but every attempt was made
  277.     to keep the code as portable as possible.  The program should
  278.     be compilable with any "standard" C compiler.  On CP/M systems
  279.     compiled with BDS C, bawk takes up about 24K.
  280.  
  281.     An input record may be no longer than 200 characters. If longer
  282.     records are encountered, they terminate prematurely and the
  283.     next record starts where the previous one was hacked off.
  284.  
  285.     A single pattern or action statement may be no longer than about
  286.     4K characters, excluding comments and whitespace.  Since the
  287.     program is semi-compiled the tokenized version will probably
  288.     wind up being smaller than the source code, so the 4K figure is
  289.     only approximate.
  290.  
  291. AUTHOR
  292.  
  293.     Bob Brodt
  294.     486 Linden Ave.
  295.     Bogota, NJ 07603
  296.  
  297. ACKNOWLEDGEMENTS
  298.  
  299.     The concept for bawk (and 3/4 of the name!) was taken from
  300.     the program "awk" written by Afred V. Aho, Brian W. Kernighan
  301.     and Peter J. Weinberger.  My apologies for any irreverences.
  302.  
  303.     The regular expression compiler/parser was borrowed from a
  304.     program called "grep" and has been highly modified.  Grep is
  305.     distributed by the DEC Users Society (DECUS) and is Copyright
  306.     (C) 1980 by DECUS.  The author acknowledges DECUS with a nod of
  307.     thanks for giving their general permission and okey-dokey to
  308.     copy or modify the grep program.
  309.  
  310.     UNIX is a trademark of AT&T Bell Labs.
  311.